<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>sprox_calypso_card_c.html</title>
<!-- Source : c:/temp/calypso/sprox_calypso_card.c -->
<!-- Doc generated on Thu Jun 24 12:26:44 2010 by johann on PC_DEV_5 -->
<!-- Generated with ROBODoc Version 4.99.8 (Specific build by PRO ACTIVE - Apr 13 2010) -->
<style type="text/css">
body
{
  background-color: #ffffff;
  color: #000000;
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  margin-left: 60px;
  margin-right: 40px;  
}
table
{
  border-collapse: collapse;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  margin-bottom: 12px;
}
td
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #dddddd; 
}
th
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;  
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  background-color: #dddddd;  
}
h1
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 18pt;
  font-weight: bold;
  margin-bottom: 36px;
  color: #000000;
  margin-left: -40px;
}
h2
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 12pt;
  font-weight: bold;
  margin-top: 48px;
  margin-bottom: 24px;
  padding-top: 2px;
  padding-bottom: 2px;
  background-color: #dddddd;
  color: #000000;
  margin-left: -40px;
}
h3
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 36px;
  margin-bottom: 24px; 
  border-style: none;
  border-top-style: solid;  
  border-width: 1px;
  border-color: #cccccc; 
  margin-left: -40px;
}
h4
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 24px;
  margin-bottom: 12px;  
}
h5
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  font-weight: bold;
  margin-top: 12px;
  margin-bottom: 2px;  
}
a
{
  color: #0000ff;
}
p
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
ul
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
li
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 550px;
  text-align: justify;
}
tt
{
  font-family: Courier, Courier New;
  font-size: 10pt;
}
pre
{
  background-color: #ffffff;
  color: #000000;
  font-size: 10pt;
}
.NAV
{
  font-size: 7pt;
}
a.NAV
{
  color: #0000cc;
}
.TOC
{
  font-size: 9pt;
  color: #888888;
}
a.TOC
{
  color: #0000ff;
}
.INDEX
{
  font-size: 9pt;
}
a.INDEX
{
  color: #0000ff;
}
.TYPE
{
  font-size: 7pt;
  color: #888888;
}
.ITEM
{
  font-weight: bold;
  color: #000088;
}
.LABEL
{
  color: #000088;
}
.HISTORY
{
  color: #006600;
}
.AUTHOR
{
  color: #006600;
}
.COPYRIGHT
{
  color: #006600;
}
.PORTABILITY
{
  color: #006600;
}
.WARNING
{
  color: #aa0000;
}

.bitinfo
{
  width: 60px;
  font-style: italic;
  text-align: center;
}

.bitnum
{
  text-align: center;
}

.bitname
{
  font-weight: bold;
  text-align: center;
}

.tabitem
{
  width: 100px;
}

.tabname
{
  width: 200px;
}

.tabdesc
{
  width: 450px;
}

.value
{
  font-family: courier;
  text-align: right;
}

.tabsepar
{
  border-top-style: solid;
  border-bottom-style: solid;
  border-width: 2px;
  border-color: #888888;
  font-style: italic;
  text-align: center;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="robo_top_of_doc"></a>
<h3 align="center">TABLE OF CONTENTS</h3>
<ul>
<li><a class="TOC" href="#robo28">CalypsoCard</a></li>
<li><a class="TOC" href="#robo56">SPROX_Calypso_CloseSecureSession</a></li>
<li><a class="TOC" href="#robo57">SPROX_Calypso_Connect</a></li>
<li><a class="TOC" href="#robo58">SPROX_Calypso_Disconnect</a></li>
<li><a class="TOC" href="#robo59">SPROX_Calypso_Exchange</a></li>
<li><a class="TOC" href="#robo60">SPROX_Calypso_OpenSecureSession</a></li>
<li><a class="TOC" href="#robo61">SPROX_Calypso_Select</a></li>
</ul>
<h3>&nbsp;</h3>


<h1><a name="robo28"><span class="TYPE">[Modules]</span><a class="LABEL" name="CalypsoCard">
CalypsoCard</a></h1>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./modules.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   SpringProxAPI :: Working with Calypso cards (application level)
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   Most parameters of the SPROX_Calypso_xxx functions directly map to Calypso
   card internal functions.
   Please refer to Calypso official documentation for any details.
</pre>
</span>


<h2><a name="robo56"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypso5fCloseSecureSession">
SPROX_Calypso_CloseSecureSession</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_Calypso_CloseSecureSession</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Close a secure session with the currently active card

 SYNOPSYS
   SWORD <strong>SPROX_Calypso_CloseSecureSession</strong>(BYTE sam_mac[4],
                                          BYTE card_mac[4]);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  sam_mac[4]         : the message authentication code provided by the Calypso SAM
                              in answer to <a class="LINK_12" href="./sprox_calypso_sam_c.html#robo64">SPROX_CalypsoSam_DigestClose</a>
 
 OUTPUTS
   BYTE  card_mac[4]        : card's answer (without the status word)
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   <a class="LINK_21" href="./sprox_calypso_h.html#robo90">CALYPSO_WRONG_MAC</a>        : bad signature (invalid sam_mac)
   Other code on any error
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   Error <a class="LINK_23" href="./sprox_calypso_h.html#robo90">CALYPSO_WRONG_MAC</a> denotes a fatal security error.
   Most of the time, this is caused by SAM and card not sharing the same key (p1 and p2
   parameters for <a class="LINK_23" href="#robo60">SPROX_Calypso_OpenSecureSession</a> not matching kif parameter for
   <a class="LINK_23" href="./sprox_calypso_sam_c.html#robo65">SPROX_CalypsoSam_DigestInit</a>, or bad kvc provided to <a class="LINK_23" href="./sprox_calypso_sam_c.html#robo65">SPROX_CalypsoSam_DigestInit</a>,
   or why not card and SAM not coming from the same network).
   This can also be caused by an erronous exchange betwen application, card, and SAM
   (for example an exchange with the card not correctly forwared to the SAM).
   Whatever the reason, transaction is cancelled by the card (and must be cancelled
   by application as well).

   On success, card_mac shall be passed to <a class="LINK_23" href="./sprox_calypso_sam_c.html#robo63">SPROX_CalypsoSam_DigestAuthenticate</a>, to check
   that the card really knows the key, and isn't cheating.
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo60">SPROX_Calypso_OpenSecureSession</a>
   <a class="LINK_37" href="#robo59">SPROX_Calypso_Exchange</a>
   <a class="LINK_37" href="./sprox_calypso_sam_c.html#robo63">SPROX_CalypsoSam_DigestAuthenticate</a>
</pre>
</span>


<h2><a name="robo57"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypso5fConnect">
SPROX_Calypso_Connect</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_Calypso_Connect</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Connect to a Calypso card in the currently select slot

 SYNOPSYS
   SWORD <strong>SPROX_Calypso_Connect</strong>(BYTE card_uid[8]);

 OUTPUTS
   BYTE uid[8]              : UID of the found card (if one)
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error 
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   This function tries to connect using the slot selected by
   <a class="LINK_23" href="#robo61">SPROX_Calypso_Select</a>.
   Contactless Calypso card may answer both to the CALYPSO_ISO14443_SLOT
   slot and to the CALYPSO_LEGACYRF_SLOT.
   Upper layer software must cope with this and ignore the second answer
   in necessary.
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo61">SPROX_Calypso_Select</a>
   <a class="LINK_37" href="#robo58">SPROX_Calypso_Disconnect</a>
</pre>
</span>


<h2><a name="robo58"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypso5fDisconnect">
SPROX_Calypso_Disconnect</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_Calypso_Disconnect</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Disconnect from the currently active Calypso card

 SYNOPSYS
   SWORD <strong>SPROX_Calypso_Disconnect</strong>(void);
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo57">SPROX_Calypso_Connect</a>
</pre>
</span>


<h2><a name="robo59"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypso5fExchange">
SPROX_Calypso_Exchange</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_Calypso_Exchange</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Exchange an APDU with the currently active Calypso card

 SYNOPSYS
   SWORD <strong>SPROX_Calypso_Exchange</strong>(BYTE send_buffer[],
                                WORD send_length,
                                BYTE recv_buffer[],
                                WORD *recv_length);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  send_buffer[]      : APDU to be sent to the card
   WORD  send_length        : size of the APDU to be sent
   WORD *recv_length        : max size for recv_buffer
 
 OUTPUTS
   BYTE  recv_buffer[]      : card's answer
   WORD *recv_length        : size of card's answer
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SIDE EFFECTS</p>
<span class="SIDE_EFFECTS"><pre class="SIDE EFFECTS">   This function implicitly forward exchanged data with the SAM if a
   a secure session is active. See <a class="LINK_18" href="#robo60">SPROX_Calypso_OpenSecureSession</a>
   Result of SPROX_Calypso_SW is updated with last status word
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="#robo57">SPROX_Calypso_Connect</a>
</pre>
</span>


<h2><a name="robo60"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypso5fOpenSecureSession">
SPROX_Calypso_OpenSecureSession</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_Calypso_OpenSecureSession</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Open a secure session on the currently active card

 SYNOPSYS
   SWORD <strong>SPROX_Calypso_OpenSecureSession</strong>(BYTE p1,
                                         BYTE p2,
                                         BYTE sam_chal[4],
                                         BYTE card_resp[],
                                         WORD *card_resp_size);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE  p1                 : the P1 parameter for open secure session command,
                              as defined in Calypso card's specification
   BYTE  p2                 : the P2 parameter for open secure session command,
                              as defined in Calypso card's specification
   BYTE  sam_chal[4]        : the challenge provided by the Calypso SAM in answer
                              to <a class="LINK_12" href="./sprox_calypso_sam_c.html#robo69">SPROX_CalypsoSam_GetChallenge</a>
   WORD *card_resp_length   : max size for card_resp_buffer
 
 OUTPUTS
   BYTE  card_resp_buffer[] : card's answer (without the status word)
   WORD *card_resp_length   : size of card's answer
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">SIDE EFFECTS</p>
<span class="SIDE_EFFECTS"><pre class="SIDE EFFECTS">   Once a secure session has been opened, any exchange between card and application
   (through <a class="LINK_18" href="#robo59">SPROX_Calypso_Exchange</a>) are implicitly forwarded to the SAM
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="./sprox_calypso_sam_c.html#robo65">SPROX_CalypsoSam_DigestInit</a>
   <a class="LINK_37" href="#robo56">SPROX_Calypso_CloseSecureSession</a>
   <a class="LINK_37" href="#robo59">SPROX_Calypso_Exchange</a>
</pre>
</span>


<h2><a name="robo61"><span class="TYPE">[Functions]</span><a class="LABEL" name="SPROX5fCalypso5fSelect">
SPROX_Calypso_Select</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>SPROX_Calypso_Select</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Select the smartcard slot for Calypso operation

 SYNOPSYS
   SWORD <strong>SPROX_Calypso_Select</strong>(BYTE slot);
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   BYTE slot                : smarcard slot number
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   MI_OK                    : success
   Other code on any error
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   Slot # 0 to 8 map to contact slots :
   0 = main slot (ISO 7816 size)
   1 = first SAM slot (micro SIM size)
   2 = second SAM slot
   ...
   For contactless operation, choose either
   CALYPSO_LEGACYRF_SLOT = Legacy Calypso protocol (Innovatron or type B')
   CALYPSO_ISO14443_SLOT = ISO-14443 protocol (type B)
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   CALYPSO_ISO14443_SLOT
   CALYPSO_LEGACYRF_SLOT
</pre>
</span>
<hr />
Generated from <b>sprox_calypso_card.c</b> on Thu Jun 24 12:26:44 2010<br />
</body>
</html>
